Xab Version 0.1

Requirements: X11R5 and PVM2.X

OVERVIEW

Xab is a set of tools which provide for the visual (X based) analysis
and debugging of PVM programs.  The basic idea behind Xab is to
instrument every PVM call so it sends a message to a monitoring process
which can either display the event or save it in file for later
analysis.  


The major components fo Xab are as follows:

abmon:  abmon is a PVM program which will read monitor messages and save
them to a file or standard out.

xab: this program will display xab events as they arrive.  They may
either be read from standard in or from a file.

libxpvm.a: this is the library which must be used for FORTRAN programs
instead of libfpvm.a

libab.a:  this library must be linked to any programs to be monitored.

topg: this shell script uses an awk script to convert the output of
abmon into picl trace format.  Due to poorly implemented awks you
we use gawk.  If you don't have gawk try awk.  If the pg.aw file
doesn't work a less sophisticated awk file, pg2.aw, can be
used.

To use xab you need to do the following:
	o include "xab.h" in your pvm C source files and recompile
	  (for fortran simply link to libxpvm.a, no need to mess with
	  include files or recompile)
	o link your pvm executables to libab.a (and libxpvm.a for fortran)
	o run abmon on some host in your virtual machine
	o run your program

To run abmon type:
	% abmon <file> 

The abmon program will enroll("xab") and write trace events to the
file you give it on the command line.  Stdout is the default file
is one is not given.

Abmon must start before any other program to be monitored.

Abmon will exit after all the processes it's monitoring have
exited via leave();

Abmon trace events are not very pretty but they are generally
human readable.  The first time stamp for an event is from the originating
processor.  The last time stamp on an event is from local abmon processor.

To run abmon and xab type:
	% abmon | xab
The abmon program will flush after every event if the output is going to 
standard out so the xab program will show the latest events.

Or if you want to keep the trace events around:
	% abmon | tee xabevfile | xab
Since tee may not flush its stdio the xab display may be out of sync.

If you want to look at the output in Paragraph type:
	% topg <fn>
and this will create a file fn.trf which you can then use
in Paragraph.  Because paragraph makes the assumption that
there is only one process per node, topg maps components to
nodes.  

For this to make sense one must assume the clocks of the machines
are synced.  If you are running ntp then things may be ok.  There
is no effort to sync clocks.  We have a sophisticated postprocessor
which will remove timing related errors but it is not stable enough
for release.  If you would like to try it send mail to adamb@cs.cmu.edu.

COMPILING

To make the files libab.a and abmon simply change to the directory
where for the appropriate architecture (ie xab/src/PMAX) and type 
make.  You may need to set the variables ARCH and PVMLIB in the makefile:

ARCH=	PMAX
PVMLIB=	$(HOME)/pvm/src/$(ARCH)/libpvm.a

Do the same for libxpvm.a but cd to ~/xab/libxpvm/ARCH.

To make xab cd to ~/xab/src then type 
	% xmkmf
	% make


EXAMPLES

You can find example programs in xab/examples/{chol,fort_examp} and example
tracefiles in xab/examples/tracefiles.

PUBLICATIONS

For publications about Xab see the June 1993 issue of IEEE Computer or

@inproceedings{beguelin:hp93,
    author="Adam Beguelin",
    title = "Xab:  A Tool for Monitoring PVM Programs",
    booktitle="Workshop on Heterogeneous Processing",
    publisher = "IEEE Computer Society Press",
    address= "Los Alamitos, California",
    month = "April",
    year = 1993,
    pages = {92--97}
}


FUTURE

I plan on makeing this tool more comprehensive.  I would like to expand
the diagnostics of xab.  It should catch things like puts and gets that
don't match.  It should also try to do some sort of timing feedback.
Finally it should be more scalable.

A big chunk of xab3 for PVM3 has been written.  I'll finish this
and release it when I get a chance.

If you have any trouble, comments or suggestions, please send me email.

	Adam

Dr. Adam Beguelin                       Carnegie Mellon University
adamb@cs.cmu.edu                        School of Computer Science, and
Assistant Research Professor			Pittsburgh Supercomputing Center
(412)268-5295 Wean                      (412)268-7866 Mellon Institute

SUPPORT

Xab was supported by Oak Ridge National Laboratory, Univerity of
Tennessee, Carnegie Mellon University -- School of Computer Science,
and the Pittsburgh Supercomputing Center.
